Software Vault: The Gold Collection/Software Vault - The Gold Collection (American Databankers) (1993).ISO/cdr35/annex10b.zip/ANNEX.DOC

Text File | 1993-01-04 | 25KB | 504 lines

                                                                   1/04/93
                                Annex 1.0b

                         Written by Jason Bassford



                             - Introduction -

   Annex will interpret the message header information produced by OLX and
any other compatible mail reader (not that I know of any - if you do I'd
appreciate knowing about it) and manipulate it in just about any way that
you wish.  Such information is further broken down into such specific
things as the 24 and 12 hour time, whether it is "am" or "pm", just what
century it is (something that will come in handy should a variation of
Annex still be in use 8 years from now...) and even the proper "suffix" to
use with the day of the month (1st, 2nd, 3rd, etc.).  This manipulation
will allow you to configure whatever header and footers you might want to
appear in your messages.
   You will be able to determine how Annex will interpret a person's name
in the header that it uses.  You may want it to be all in Caps or only the
first letter, or you may even want to change it completely so that
whenever a certain name appears the header reads, "My friend was talking
to me about..." instead of "Michael Smith was talking to Jason Bassford
about..."  Every time Annex encounters a name that its not familiar with
it will stop and prompt you to enter what you would like it to use in
place of it.  Once it knows what you want it to use it will then use that
"association" automatically.
   In addition to the standard forms of headers, Annex also supports
special Internet headers that are sometimes required by BBSs in order to
properly send Internet mail.  In this way you can Reply to a message in
OLX and never worry about having to enter their Internet address before
writing your message to them.  (Lord knows, before I wrote Annex I more
than once had Internet mail bounced back to me because I'd forgotten to
include the recipient's Internet address in the body of a message...)
   (Note that both normal and Internet headers will not be available if the
message you are writing is *new*.  Headers are only possible if you are
replying to an existing message for which OLX has the necessary
information to pass on to Annex.  Footers, on the other hand, are always
available.)
   The footer section of Annex lets you control the format that you wish
to use for your taglines, and any other additional "footer" messages you
might wish to include, such as placing your signature before the tearline
in the actual message itself.  The one thing to be aware of about Annex's
tagline manipulation is that the taglines it uses are selected at random
by the program.  If you want to get a *specific* tagline to be used with
your message there is a fairly simple method to do so (which is described
at the end of this document) but it is not as simple as it would be with a
program designed solely to manage your taglines.  If what you are
interested in is simply a tagline manager then Annex 1.0 probably isn't
going to be what you're looking for.



                              - Background -

   This is an OLX/SLMR header and footer utility that I have been working
with, on and off, since the Summer of '92.  It all started with a friend
of mine who innocently suggested that I create a small header utility for
him to use with his OLX messages.  Once I started he kept suggesting more
features he'd like to see it have, and I also came up with some of my own
ideas.  When the header portion of Annex was finished I put the project
aside for a while as I was busy with other things and the reason it had
been created in the first place was solely as a header utility.
   Then I happened to order OLX 3.0 along with the new Qmodem Pro from
Mustang Software.  While I'm quite happy with both products, I was
dismayed to realize that the tagline signature OLX used was "QMPro 1.0
41-4932".  Not only did I not want the serial number in my taglines (as it
takes up too much space for my actual tags to comfortably fit) but I also
wanted it to instead display "OLX" - which program is the real reason I'd
ordered the upgrade package in the first place.  So after trying
unsuccessfully to sway the MSI staff to send me a "patch" of some sort to
address these problems, I decided to just go ahead and write my own
footer/tagline utility that would let me do what I wanted.  In short, I
picked up my earlier work on Annex once more.



                               - Licensing -

   There are several things that you should note about this utility. First
of all, and probably most important right now, is that I am distributing
this as Shareware.  Yet, is not crippled in any way and, contrary to the
normal concept of Shareware it isn't in any way different from the
registered version.  In fact, there *is* no "registered" version per se -
the program that exists here is exactly what I am currently working with
on my own machine.  Why then do I call it Shareware?  Simply because I
will put "registered users" on a list for the purposes of any future
releases that I might distribute.  I will take note of any registered
user's comments and suggestions for future versions, and offer any support
that is necessary in order to get it running smoothly.  If it becomes
apparent that there is a bug in the program that requires me to distribute
a maintenance release (while I've tested it extensively myself there is
always this possibility with different machines) I will mail this directly
to everyone on my list as soon as possible.  Anyone wishing to register
Annex need only send me a note informing me of this.  Other than the cost
of the postage stamp <grin> this process is free.
   Also, I do *not* distribute this along with my permission for the
program to be rewritten or altered in any way.  It is to be used *as is*,
and any changes to it have to come through me.  Additionally, if this is
distributed to a BBS (and I *do* encourage this) it should contain all of
the files that are listed later in the "Installation" section.  In other
words, it must be uploaded just as you downloaded it.  I'm not familiar
with the legalities involved here, however I can tell you that at the very
least I would be considerably "upset" if I find these conditions of use to
be ignored by someone.  I'm not sure just what action I would take,
although it would most likely not be pleasant. <grin>



                                - History -

Annex1.0a:

   This is a maintenance release for Annex 1.0 which I discovered, much to
my horror after I had uploaded it to various BBSs, contained some out of
date code, resulting in some program bugs.  Please accept my apologies.


Annex1.0b:

   This release allows for the configurable placement of footer text
before as well as after the message's tearline.  This will allow you to
place custom signatures in the body of your message, followed by a
tearline and then whatever tagline you want.



                             - Installation -

   The following files should be included in annex10.zip:

annex.doc   -  Annex documentation.  You're reading it.  (I always thought
               that this entry was pretty self-evident. <grin>)
annex.bat   -  A sample batch file showing how to implement Annex.  It
               will have to be modified to suit your text editor and other
               setup parameters.
header.exe  -  The program that produces header text in your messages.
header.txt  -  The text file controlling what the header text will look
               like.
header.net  -  The text file determining the format of any Internet header
               message.
footer.exe  -  The program that controls footer text.
footer.txt  -  The text file controlling what the footer text will look
               like.

   Copy all of these files to your OLX directory (although the program
will work just fine without annex.doc, you might want to keep it for
reference anyway).  To get Annex to work you have to tell OLX to run a
batch file in the Editor section of the Options (or Configuration) menu.
This batch file will first run the header program, then whatever text
editor you use, and finally the footer program.  I have called the batch
file that I use "annex.bat", although you can always name yours something
else if you wish.  This is what my OLX setup looks like:

Editor command line    c:\olx\annex

Quoted original message file REPLY.MSG
File to take reply text from REPLY.MSG

   And the following is what my included "annex.bat" file contains in order
to run Annex with OLX 3.0:

@echo off
cls
cd \olx
header %1
b %1
footer tagline.olx %1

   Note a couple of things here.  First of all the batch file changes
directories to the main OLX directory (in which the Annex files are to be
found).  If the directory in use is not the OLX directory Annex will not
work properly.  Secondly, make sure that you edit the OLX pathnames
appropriately, as according to your own setup.  The "b %1" line simply runs
my text editor - you should replace this with whatever commands are
necessary to run your own editor.  Lastly, this should work as-is with
earlier version of OLX also.  The only difference I would make if I
weren't using 3.0 is that I would add a line to run an external spell
checker (mine used to be "spell %1") after the last line.
   You must configure OLX to include its own header in the quoted reply in
the Replies section of the Options (Configuration) menu.  You must also
turn OLX's own taglining off by setting the Enable Taglines to "Off" in
the same section.



                              - Using Annex -

   As the program runs it will create a file called "header.inf" which
contains a list of names and the associations that you assign to them.  At
first, Annex will keep interrupting itself before writing the header
information and prompt you to enter how you want all of the new names not
found in this file to appear in your replies.  As your list of names grows
though this will happen less often, as it finds fewer new names, and it
will quickly be mostly invisible.



                          - The Header Program -

   If it finds a name that is not in the "header.inf" file, it will tell
you this and give you two choices. One of which is a format of the name in
which the first letter of each "word" is in Capital and all others are in
small case.  The second allows you to enter a different format than this
"default" if you so wish.  Say that the name it is looking at is "MICHAEL
SMITH". You would see the following:


Name not found in data file...


  1 - Michael Smith

  2 - Custom format / Internet header.


Please enter the desired format for future use:


   The first option is self-explanatory and what I use almost all the
time.  However, say that Michael prefers being referred to as "Mike".
If you want it to automatically put "This message was from Mike..."
then select the second option.  You will now see a screen that looks
like this:


The original name is 'MICHAEL SMITH'.


  Enter the new name:

    Internet address:


   (The cursor will be right after the "Enter the new name:" line.)
Enter "Mike Smith" on the first line.  When you reach the second line
it will change to read:

    Internet address: [None]

   Simply hit <Return>, as we are not dealing with Internet E-Mail in this
example.  From then on when Annex encounters the name, it will replace it
with your selection.  If you later decide that you want to change an
association just load the "header.inf" file into your text editor and edit
it manually - it is sorted alphabetically by first name.  If editing an
"Internet" name, be sure to follow the format that the program uses for
those.



                      - Internet E-Mail and Headers -

   I don't know if you have dealt with this before or not.  It's private
mail that you send to people at certain "Internet addresses."  For
instance, my own Internet address is "[e-mail]".  If I were
to send you Internet E-Mail, OLX would display it as being "From:
[e-mail]".  This, obviously, is not what you want put in
the header line.  So, when prompted, you would select the second option
and make my new name "Jason Bassford".  However, if you wanted to send
Internet E-Mail back to me (as you probably would) the procedure for this
is a bit more complex.  What I have to do on *my* BBS (and I think it's
similar for other bulletin boards) is to make the To: line in OLX read
"USENET GATEWAY".  Then, in the body of the message, my first line is
"To: " followed immediately by the person's Internet address, and then a
blank line.  On the third line the actual message can start.
   So, if you want to send me Internet E-Mail, rather than just hitting
<Return> to go past the "Internet address: [None]" line, you would enter
my address ("[e-mail]").  Header will then create *two*
headers.  One for Internet and the other for the normal message.  In this
case it would read something like this:


To: [e-mail]

The following was said by Jason Bassford...


   Just as you may alter the header text by changing the file "header.txt"
you may alter the Internet header text (I wasn't sure if it always
followed the "To: address" format so I allowed for it to be changed too)
by modifying the file "header.net".
   Note that you may have more than one entry for the same person in
certain circumstances.  For instance, I have a friend who writes to me
both via Internet and on some network Conferences.  Hence, I have an
association for "GLEN CAMPBELL" as well as for "GLEN.CAMPBELL@ROSE.
COM".  Remember, it's the *name* not the person that the program
recognizes.

   (Special note:  Due to a programming "glitch" that I'm aware of there is
a potential problem editing the Internet address.  You cannot change the
*first* character of the address directly.  Say, for example, that I had
meant to type "glen" but instead typed "flen".  In order to correct such a
mistake, you have to delete everything after the first character (in this
case only the "f" would remain) and then hit <Enter> *as if* this were
correct.  The program will return to it's previous state and prompt you
again for the correct address.)



                    - Creating Header and Footer Text -

   Header and footer text is generated by editing text files (header.txt
for headers, header.inf for Internet headers, and footer.txt for footers).
The text in these files will be read and placed in your messages at the
appropriate places. Things like the name of the person the message is
from, the date it was sent, or, as in the case of a footer, the date the
reply was written, are represented by "variables", as explained below.
Right now header text will word-wrap at 70 characters.  I haven't yet set
this up to allow the user to change this value.  (If any interest is
expressed in having this value changed, I will send a "patch" to any
*registered* user that requests it.)  So, if a word goes past 70
characters it will jump down to the next line.  I set it at 70 (as I have
my text editor for all E-Mail messages) so that it is easily quotable, not
going past the right 80 column margin.  Footer text will *not* word wrap.
Due to it's nature this would not be advantageous in my opinion (although
I'd be happy to hear any comments if you feel otherwise).  So it is up to
you to monitor the length of individual footer lines.



                      - Header and Footer Variables -

   Even though the text may appear on separate lines in the text files it
will *not* be treated as being as such when read in as a header or footer.
For instance the following

On
three
lines.

would appear on one line only: "On three lines."  To make it appear on
three separate lines you must explicitly put in carriage returns.  To tell
Annex to put in a carriage return you would put a carriage return
"variable" into the text.  All variables are enclosed by "|" characters
(located above the "\" key).  So, to get the above on three separate lines
our text file would look like this:

On|CR|
three|CR|
lines.

   And, if this is header text, to get the actual message to appear
following it and a blank line, you would need to add a "|CR|" both to the
end of the last line as well as another one after that. (Also note that I
could have just as easily written all of the above on one line
(On|CR|three|CR|lines.) and it still would have come out as three lines in
the end. It's purely for the sake of readability that I would choose the
first format.)
   If for some reason you wish to actually include a "|" character in the
text of the message you can do so by using two in a row ("||").  Also, if
you do not use a "legal" variable it will appear as text (if you made a
typing mistake and used "|C|", forgetting the "R", it would not issue a
carriage return but, for example, print "three|C|lines.").

   Here are the variables that you can use:

|FROM|        Header text only.
|TO|          Header text only.
|SUBJECT|     Header text only.
|MONTH|       Numerical value (December is "1").
|MONTH2|      As above but two digits (December is "01").
|LMONTH|      The full month name ("December").
|SMONTH|      The shortened month name ("Dec").
|DAY|         Numerical value (January "21"st).
|DAY2|        As above but two digits ("9" becomes "09").
|SUFFIX|      Appropriate termination for the numeric day ("21" "st").
|LDAY|        The full day name ("Wednesday").
|SDAY|        The shortened day name ("Wed").
|CENTURY|     The "first part" of the year (1992 is "19").
|YEAR|        The "second part" of the year (1992 is "92").
|TIME24|      The 24 hour time.
|TIME12|      The 12 hour time ("13:03" becomes "1:03").
|TIME12A|     As above but "13:03" would become "01:03").
|HOUR|        The time "period" (13:03 is "pm").
|BBS|         The name of *your* BBS.  Header text only.
|CONFERENCE|  Header text only.
|NUMBER|      The number of the message.  Header text only.
|REFERENCE|   (These OLX variables are both included although I believe
|RECEIVED|    they will always read something to the affect of "None"
              or "No", and I haven't figured out if they are worthwhile
              yet or not!  Also, only useable in header text.)

|CR|          Carriage return.
||            Pipe ("|") character.

|ADDRESS|     Internet header text only.  Note that "header.net" can only
              use this variable and the two special ones above.  All of the
              rest have no special meaning for it.
|TEARLINE|    Footer text only.
|TAGLINE|     Footer text only.


   Note: In the case of header text, time and date variables pertain to
         when the quoted message was sent.  If used in footer text, then
         they will refer to when *your* message was written.


   One last point.  The header.txt, header.net, and footer.txt files may
be of any length.  The program interprets each text character one at a
time and then moves on to the next.  You could include a header that was a
copy of "War And Peace", or compose a similarly long "farewell" speech for
your footer/tagline, if you wished.  But I certainly wouldn't recommend
it. <grin>



                       - Footer Text and Tearlines -

   Any lines of text that are written to you message *before* a tearline
will be just as they appear in the footer.txt file, however this is not
precisely true of text *following* a tearline.  Each line of such text
will be automatically indented one space by the program so that it lines
up properly with all other Net taglines that will be later appended.  This
is not just for aesthetic reasons, but to guarantee that there are no Net
"hiccouphs" due to improperly formatted tagline text.
   Finally, the placement of a tearline in your message is not automatic.
If you want it to contain a tearline you must explicity enter a
"|TEARLINE|" variable in the footer.txt file - make sure to also issue a
carriage return ("|CR|") after that variable as well so that it will
function properly as a tearline.  If you don't use the "|TEARLINE|"
variable but instead decide to simply use "---", Annex will not interpret
this properly as anything other than "meaningless" text for the purposes of
indenting text afterwards as explained in the above paragraph.  Multiple
tearlines *are* allowed by Annex if you write your footer.txt file to so
indicate them, but they will serve no special function other than to most
likely confuse the Net and some other users upset.  So I would recommend
against using them.



             - Alternate Tagline Files and Specific Taglines -

   If you look at the command syntax for running footer.exe in the batch
file you will note that it is different from that used with header.exe.
The latter requires only that you specify the name of the message text
file.  Footer.exe however, *also* requires the name of the text file that
contains your taglines.  Because of this it is possible to set it to a
tagline file other than "taglines.olx".  There may be some reason that you
*don't* want to use that filename and I thought it was silly to have Annex
assume that you did.  To use a different tagline file just edit the
"footer" line in the batch file controlling your message replies to
reflect this change.
   Similarly, it is possible to "force" Annex to append a specific
tagline, even though it is not written to do so.  All you have to do is
make sure that the tagline file that footer.exe is assigned contains only
one tagline - the one you want.  Even given it's randomness, it would be
hard pressed to come up with a number between 1 and 1 that didn't
correspond to that tagline. <grin>  This requires shelling out to Dos from
your OLX session.  Either copy your current tagline file to somewhere
else, and then edit the original, or create a new file with only the
tagline you want and edit your batch file so that footer.exe works with
that one instead.  Both methods require some work, but it's not that big a
hassle if you don't use specific taglines often.  (Just remember to later
change your setup back to what it was originally...)



                             - General Notes -

   There are a couple of things about the way Annex works that you might
like to know - although I doubt you will ever come across them.  First of
all, make sure that the *first* tagline in your tagline file is *not*
simply a number.  Because OLX places a number at the beginning of its
tagline file, I've had to make Annex ignore any such numbers if they exist
so it doesn't think that *it* is one of your taglines.
   Secondly, all text after a line containing *only* "---" at the left
margin will be deleted.  This is the only way I could have Annex handle
tear-lines and footers.  If you enter a message and then re-edit it, Annex
has to first delete the existing tear-line and footer information.  If it
didn't, you'd end up with increasing numbers of tear- and taglines
appended to the bottom of your re-edited messages.
   However, I find it *very* unlikely that either of these specific
conditions would be fulfilled in such a way as to cause you difficulties
with your messages! <grin>  If not something to be "warned" about, then
they are at least something you might find interesting to know, in terms
of how the program functions internally.



                              - Conclusion -

   I hope that I have explained the various workings of the program
satisfactorily.  As I say, this is still an "early" version - but, after
getting several requests for it recently, I decided to go ahead and
distribute it anyway.  Any comments or questions are welcome.  My mailing
address until May 1992 is:

59 Glenforest Rd.
Toronto, Ontario
Canada  M4N 1Z7

After that date I will be moving somewhere else when my lease expires
<grin>, but mail can always reach me at:

416 Keewatin Ave.
Toronto, Ontario
Canada M4P 2A5

My Internet address is "[e-mail]".

   Thank you for taking the time to read this, and I hope you find the
program useful!